RCS Promotion APIs
The RCS Promotion APIs enable businesses to create and launch rich, interactive promotional campaigns using Rich Communication Services (RCS). These APIs support advanced messaging features including rich cards, carousels, and interactive buttons.
Prerequisites
- RCS Business Account: Active RCS Business Messaging account with verified brand
- Msgkart Account: An active Msgkart account with API Key
- Approved Rich Cards: Pre-approved RCS message templates with rich media
Launch RCS Promotion
Creates and launches a new RCS promotional campaign with rich media content.
Request Syntax
POST api/v2/promotion/{{msgkartId}}/template/launch?name={{nameOfTargetList}}
Form Data
Use multipart/form-data to upload the CSV file along with the request body.
file: {{csvFile}}
body: JSON
{
"businessId": "{{msgkartId}}",
"name": "{{promotionName}}",
"promotionType": "IMMEDIATE",
"promotionBase": "TEMPLATE",
"promotionTemplateType": "TEMPLATE",
"template": {
"name": "{{tempalteName}}",
"id": "{{tempalteId}}",
"language": "{{templateLanguage}}",
"components": [
{
"type": "CAROUSEL",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "BODY",
"variables": [
{ "type": "text", "value": "${name}" },
{ "type": "text", "value": "${phone}" },
{ "type": "text", "value": "${language}" },
{ "type": "text", "value": "${businesssubscriberid}" },
{ "type": "text", "value": "${name}" },
{ "type": "text", "value": "${language}" },
{ "type": "text", "value": "${phone}" }
]
},
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "https://image.jpeg"
}
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "https://image.jpeg"
}
}
]
}
]
}
]
},
"channelType": "rcs"
}
Launch RCS Promotion On an Uploaded list
Launches an RCS promotional campaign targeting contacts from an uploaded CSV file with rich interactive content.
Request Syntax
POST api/v2/promotion/{{msgkartId}}/template/launch?name={{nameOfTargetList}}
Request Body
{
"businessId": "{{msgkartId}}",
"name": "{{promotionName}}",
"promotionType": "IMMEDIATE",
"promotionBase": "TEMPLATE",
"promotionTemplateType": "TEMPLATE",
"template": {
"name": "{{tempalteName}}",
"id": "{{tempalteId}}",
"language": "{{templateLanguage}}",
"components": [
{
"type": "CAROUSEL",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "BODY",
"variables": [
{
"type": "text",
"value": "${name}"
},
{
"type": "text",
"value": "${phone}"
},
{
"type": "text",
"value": "${language}"
},
{
"type": "text",
"value": "${businesssubscriberid}"
},
{
"type": "text",
"value": "${name}"
},
{
"type": "text",
"value": "${language}"
},
{
"type": "text",
"value": "${phone}"
}
]
},
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "https://image.jpeg"
}
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "https://image.jpeg"
}
}
]
}
]
}
]
},
"channelType": "rcs"
}
Properties
| Property | Description | Sample |
|---|---|---|
campaignName | Name of the RCS promotional campaign | Black Friday Sale |
messageType | Type of RCS message | rich_card, carousel, standalone |
content | Rich content object with title, description, and media | See request body |
title | Title of the rich card | Exclusive Deals |
description | Description text for the card | Get up to 70% off |
mediaUrl | URL of the media (image/video) | https://example.com/img.jpg |
mediaHeight | Height of the media | SHORT, MEDIUM, TALL |
suggestions | Interactive action buttons | Array of suggestion objects |
uploadedListId | ID of the uploaded contact list | list_rcs_456 |
targetAudience | Target audience segment | all, premium, engaged |
scheduledTime | Scheduled launch time (ISO 8601 format) | 2024-11-29T00:00:00Z |
Get Promotions
Retrieves all RCS promotions for a specific business account.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}?channel=rcs
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Channel type (use rcs for RCS) |
Response Body
{
"promotions": [
{
"promotionId": "5d58cb288b0d46ffbe839fec303f8bb4",
"businessId": "107698525673716",
"msgkartId": "107698525673716",
"name": "Adil testing",
"channelType": "rcs",
"status": "Completed",
"createdBy": null,
"promotionType": "IMMEDIATE",
"targetSource": "CSV",
"targetType": "Digitap 1.csv_1765385758146",
"flowId": null,
"flowName": null,
"promotionBase": null,
"attributionWindow": 0,
"promotionEndTime": 1765385829,
"createdDate": 1765385766
}
]
}
Get Promotion Statistics Report
Retrieves detailed statistics and analytics for a specific RCS promotion campaign.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}/statistics/{{promotionId}}/report?channel=rcs
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Channel type (use rcs for RCS) |
Response Body (CSV Format)
Name,Phone,Status,Timestamp,Error,FlowId,FlowName,RetryCount,TemplateName,Language
Datta,919986014713,read,10 Dec 2025 10:27 PM,null,null,0,cpr_adil,en_US
Joel,919895566812,failed,10 Dec 2025 10:27 PM,This message was not delivered to maintain healthy ecosystem engagement.,null,null,0,cpr_adil,en_US
}
Get Promotion Stats
Retrieves real-time statistics for a specific RCS promotion.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}/{{promotionId}}/stats?channel=rcs
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Channel type (use rcs for this endpoint) |
Response Body
{
"attempted": 8,
"failed": 2,
"sent": 0,
"delivered": 0,
"read": 6,
"interacted": 0,
"optout": 0,
"statsReport": [
{
"attempted": 8,
"failed": 2,
"sent": 0,
"delivered": 0,
"read": 6,
"interacted": 0,
"optout": 0,
"promotionRetryNumber": 0
}
]
}
Update Promotion Status
Updates the status of an RCS promotion (stop or cancel).
Request Syntax
PATCH /api/v2/promotion/{{msgkartId}}/{{promotionId}}?channel=rcs
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion to update |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Channel type (use rcs for RCS) |
Request Body
{
"type": "status",
"status": "Stopped"
}
Status Values
| Value | Description |
|---|---|
Stopped | Temporarily stop the promotion (can be resumed) |
Cancelled | Permanently cancel the promotion (cannot be resumed) |
Response Body
{
"promotionId": "a33a29a41afb40e5a5bca1d333b8d998",
"businessId": "107698525673716",
"msgkartId": "107698525673716",
"name": "response",
"targetListId": "4d47d5f540a74abea1b23f4ebeb4664d",
"targetListName": "adilMaheshHariKris",
"phoneNumberId": "126875363728090",
"template": {
"name": "abc_adil_nawaz",
"id": "701692262430813",
"language": "en_US",
"category": "MARKETING",
"components": [
{
"variables": [
{
"type": "text",
"value": "Adil"
}
],
"type": "BODY"
},
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "https://media.msgkart.com/107698525673716/48b4e7cead794afdbb9b42c3eb417481.jpeg",
"fileName": "msgkart_healthcare"
}
}
]
},
"createdDate": 1765777610,
"startTime": 0,
"mostRecentStartTime": 0,
"status": "Cancelled",
"createdBy": "a599947d-bc5c-4b45-b93c-5a318e2e2243",
"promotionType": "IMMEDIATE",
"scheduleTime": "0",
"targetSource": "CSV",
"tagSearchCriteria": "ANY",
"retryPromotion": true,
"maxRetries": 3,
"retriesLeft": 3,
"channelType": "rcs",
"batchSize": 0,
"batchTimer": 0,
"staggered": false,
"subscriberLimitPerGroup": 0,
"attributionWindow": 0,
"promotionBase": "TEMPLATE",
"promotionEndTime": 1765777679,
"callCampaign": false,
"utilityTemplateIndex": 0,
"stopOnCategoryUpdate": false
}